Basic Usage

Command line Flags

While it is certainly not necessary to know all possible command line flags for Schemey, there are some which are important and it wouldn’t hurt to memorize them.

Schemey offers several different flags for use on the command line. The full list is:

  • -c --compile: Given the path to a source file, compile the source file into
    bytecode, and write it to a file. If a second argument is given the bytecode will be written to that file, otherwise a file is created in the same directory as the source file, and the bytecode is written there.
  • -d --decompile: Given the path to a compiled bytecode file, decompile the bytecode in
    the file, and display a helpful representation of the bytecode structure.
  • -e --execute: Given the path to a compiled bytecode file, load in the file and execute it
    via the virtual machine.
  • -rn --run: Given the path to a bytecode file, compile the file to
    bytecode, write the bytecode to a file, load the file back in, and run the file via the virtual machine. This is basically a combination off the functionality of all the above flags.
  • -r --repl: Run the REPL for Schemey(See Running the REPL below).
  • -t --test: Run the tests for the Schemey interpreter.

Running the REPL

The REPL is a powerful feature which allows you to quickly test your code, without having to recompile a source file over and over.

To use the REPL, navigate to the Schemey/src/ directory, in the source and run the schemey.py file. This is the main file of the source code and used to run Schemey from the command line. After running the file, the REPL will open with a greeting message, some brief instructions on usage, and a prompt eg:

 C:\Schemey\src> python schemey.py
 Welcome to the Schemey repl. Type in expressions and press
 enter to evaluate them, or type in "exit" to quit.

[schemey]>

After the REPL is open, you can type in an expression and see it evaluated immediately:

[schemey]> (+ 1 2)
=> 3
[schemey]> (+ 1 2 3 4 5 6 7 8 9 10)
=> 55

To “break” out of the REPL, you can type in the exit command. This will return you back into the command prompt:

[schemey]> exit

C:\Schemey\src>

The REPL offers the distinct advantage of being able to quickly and easily test expressions, and see their results immediately, instead of having to re-compile a source file again and again to see the updated changes.

Warning

Multi-line expressions(expression which span multiple lines) are currently not allowed in the REPL. eg.

[schemey]> (+ 1

At line 1:

(+ 1
    ^

Unmatched parentheses at end of input
[schemey]>

Compiling & Decompiling source files

As said above, the flags -c --compile and -d --decompile correspond to compiling and decompiling a source file respectively.

To compile a source file, pass the -c or --compile flag to schemey.py, along with at least on argument to the flag which is the source file to be compiled. If a second argument is given, the bytecode will be written to that path. Otherwise, a file is created with the same name as the source file’s, with a .pcode extension.

To decompile a file into human-readable output, pass the -d or --decompile flag schemey.py. One argument is required, which is the path to the compiled bytecode file. After de-compilation, a helpful representation of the structure of the bytecode file is printed out(the output is actual repr(CodeObject()). See bytecode.py for the implementation of CodeObject).

Executing a source file

There are two ways one can execute a source file.

  • You can first compile the source file(see Compiling & Decompiling source files), then use the -e or --execute flags to execute the bytecode file. The one argument the two flags take is the path to a bytecode file.

    You might wonder why one would want to compile a program in this manner, when they could simply do everything all at once using the --run flag (see below).

    The reason for this design is so SchemeyVM is able to execute bytecode compiled by compilers other than the one in this project. In other words, this design allows anyone to create a compiler which targets SchemeyVM’s bytecode, and the virtual machine will be able to execute files created by those compilers.

  • The second way you can run a source file - and will probably the most common - is using the -rn --run flags, which require one argument; the path to the source file. The source file will then be automatically compiled and executed.

Note

all output by the virtual machine is directed to sys.stdout. If you would like this changed, the VirtualMachine class’s constructor allows you to specify an output stream(see virtual_machine.py for more details).